home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / KoStore.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-30  |  11.2 KB  |  382 lines
  1. // -*- c-basic-offset: 2 -*-
  2. /* This file is part of the KDE project
  3.    Copyright (C) 1998, 1999 David Faure <faure@kde.org>
  4.  
  5.    This library is free software; you can redistribute it and/or
  6.    modify it under the terms of the GNU Library General Public
  7.    License as published by the Free Software Foundation; either
  8.    version 2 of the License, or (at your option) any later version.
  9.  
  10.    This library is distributed in the hope that it will be useful,
  11.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.    Library General Public License for more details.
  14.  
  15.    You should have received a copy of the GNU Library General Public License
  16.    along with this library; see the file COPYING.LIB.  If not, write to
  17.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.  * Boston, MA 02110-1301, USA.
  19. */
  20.  
  21. #ifndef __koStore_h_
  22. #define __koStore_h_
  23.  
  24. #include <qstring.h>
  25. #include <qstringlist.h>
  26. #include <qiodevice.h>
  27. #include <qvaluestack.h>
  28. #include <koffice_export.h>
  29.  
  30. class QWidget;
  31.  
  32. class KURL;
  33.  
  34. /**
  35.  * Saves and loads KOffice documents using various backends. Currently supported
  36.  * backends are ZIP, tar and directory.
  37.  * We call a "store" the file on the hard disk (the one the users sees)
  38.  * and call a "file" a file inside the store.
  39.  */
  40. class KOSTORE_EXPORT KoStore
  41. {
  42. public:
  43.  
  44.   enum Mode { Read, Write };
  45.   enum Backend { Auto, Tar, Zip, Directory };
  46.  
  47.   /**
  48.    * Open a store (i.e. the representation on disk of a KOffice document).
  49.    *
  50.    * @param fileName the name of the file to open
  51.    * @param mode if KoStore::Read, open an existing store to read it.
  52.    *             if KoStore::Write, create or replace a store.
  53.    * @param backend the backend to use for the data storage.
  54.    * Auto means automatically-determined for reading,
  55.    * and the current format (now Zip) for writing.
  56.    *
  57.    * @param appIdentification the application's mimetype,
  58.    * to be written in the file for "mime-magic" identification.
  59.    * Only meaningful if mode is Write, and if backend!=Directory.
  60.    */
  61.   static KoStore* createStore( const QString& fileName, Mode mode, const QCString & appIdentification = "", Backend backend = Auto );
  62.  
  63.   /**
  64.    * Create a store for any kind of QIODevice: file, memory buffer...
  65.    * KoStore will take care of opening the QIODevice.
  66.    * This method doesn't support the Directory store!
  67.    */
  68.   static KoStore* createStore( QIODevice *device, Mode mode, const QCString & appIdentification = "", Backend backend = Auto );
  69.  
  70.   /**
  71.    * Open a store (i.e. the representation on disk of a KOffice document).
  72.    *
  73.    * @param window associated window (for the progress bar dialog and authentification)
  74.    * @param url URL of the file to open
  75.    * @param mode if KoStore::Read, open an existing store to read it.
  76.    *             if KoStore::Write, create or replace a store.
  77.    * @param backend the backend to use for the data storage.
  78.    * Auto means automatically-determined for reading,
  79.    * and the current format (now Zip) for writing.
  80.    *
  81.    * @param appIdentification the application's mimetype,
  82.    * to be written in the file for "mime-magic" identification.
  83.    * Only meaningful if mode is Write, and if backend!=Directory.
  84.    *
  85.    * If the file is remote, the backend Directory cannot be used!
  86.    *
  87.    * @since 1.4
  88.    * @bug saving not completely implemented (fixed temporary file)
  89.    */
  90.   static KoStore* createStore( QWidget* window, const KURL& url, Mode mode, const QCString & appIdentification = "", Backend backend = Auto );
  91.  
  92.   /**
  93.    * Destroys the store (i.e. closes the file on the hard disk)
  94.    */
  95.   virtual ~KoStore();
  96.  
  97.   /**
  98.    * Open a new file inside the store
  99.    * @param name The filename, internal representation ("root", "tar:/0"... ).
  100.    *        If the tar:/ prefix is missing it's assumed to be a relative URI.
  101.    * @return true on success.
  102.    */
  103.   bool open( const QString & name );
  104.  
  105.   /**
  106.    * Check whether a file inside the store is currently opened with open(),
  107.    * ready to be read or written.
  108.    * @return true if a file is currently opened.
  109.    */
  110.   bool isOpen() const;
  111.  
  112.   /**
  113.    * Close the file inside the store
  114.    * @return true on success.
  115.    */
  116.   bool close();
  117.  
  118.   /**
  119.    * Get a device for reading a file from the store directly
  120.    * (slightly faster than read() calls)
  121.    * You need to call @ref open first, and @ref close afterwards.
  122.    */
  123.   QIODevice* device() const;
  124.  
  125.   /**
  126.    * Read data from the currently opened file. You can also use the streams
  127.    * for this.
  128.    */
  129.   QByteArray read( unsigned long int max );
  130.  
  131.   /**
  132.    * Write data into the currently opened file. You can also use the streams
  133.    * for this.
  134.    */
  135.   Q_LONG write( const QByteArray& _data );
  136.  
  137.   /**
  138.    * Read data from the currently opened file. You can also use the streams
  139.    * for this.
  140.    * @return size of data read, -1 on error
  141.    */
  142.   Q_LONG read( char *_buffer, Q_ULONG _len );
  143.  
  144.   /**
  145.    * Write data into the currently opened file. You can also use the streams
  146.    * for this.
  147.    */
  148.   virtual Q_LONG write( const char* _data, Q_ULONG _len );
  149.  
  150.   /**
  151.    * @return the size of the currently opened file, -1 on error.
  152.    * Can be used as an argument for the read methods, for instance
  153.    */
  154.   QIODevice::Offset size() const;
  155.  
  156.   /**
  157.    * @return true if an error occurred
  158.    */
  159.   bool bad() const { return !m_bGood; } // :)
  160.  
  161.   /**
  162.    * @return the mode used when opening, read or write
  163.    */
  164.   Mode mode() const { return m_mode; }
  165.  
  166.   /**
  167.    * Enters one or multiple directories. In Read mode this actually
  168.    * checks whether the specified directories exist and returns false
  169.    * if they don't. In Write mode we don't create the directory, we
  170.    * just use the "current directory" to generate the absolute path
  171.    * if you pass a relative path (one not starting with tar:/) when
  172.    * opening a stream.
  173.    * Note: Operates on internal names
  174.    */
  175.   bool enterDirectory( const QString& directory );
  176.  
  177.   /**
  178.    * Leaves a directory. Equivalent to "cd .."
  179.    * @return true on success, false if we were at the root already to
  180.    * make it possible to "loop to the root"
  181.    */
  182.   bool leaveDirectory();
  183.  
  184.   /**
  185.    * Returns the current path including a trailing slash.
  186.    * Note: Returns a path in "internal name" style
  187.    */
  188.   QString currentPath() const;
  189.  
  190.   /**
  191.    * Returns the current directory.
  192.    * Note: Returns a path in "internal name" style
  193.    */
  194.   QString currentDirectory() const;
  195.  
  196.  
  197.   /**
  198.    * Stacks the current directory. Restore the current path using
  199.    * @ref popDirectory .
  200.    */
  201.   void pushDirectory();
  202.  
  203.   /**
  204.    * Restores the previously pushed directory. No-op if the stack is
  205.    * empty.
  206.    */
  207.   void popDirectory();
  208.  
  209.   /**
  210.    * @return true if the given file exists in the current directory,
  211.    * i.e. if open(fileName) will work.
  212.    */
  213.   bool hasFile( const QString& fileName ) const;
  214.  
  215.   /**
  216.    * Imports a local file into a store
  217.    * @param fileName file on hard disk
  218.    * @param destName file in the store
  219.    */
  220.   bool addLocalFile( const QString &fileName, const QString &destName );
  221.  
  222.   /**
  223.    * Imports a local directory
  224.    * @param dirPath path to the directory on a disk
  225.    * @param dest path in the store where the directory should get saved
  226.    * @return the directory index
  227.    */
  228.   QStringList addLocalDirectory( const QString &dirPath, const QString &dest );
  229.  
  230.  
  231.   /**
  232.    * Extracts a file out of the store
  233.    * @param srcName file in the store
  234.    * @param fileName file on a disk
  235.    */
  236.   bool extractFile( const QString &srcName, const QString &fileName );
  237.  
  238.   //@{
  239.   /// See QIODevice
  240.   bool at( QIODevice::Offset pos );
  241.   QIODevice::Offset at() const;
  242.   bool atEnd() const;
  243.   //@}
  244.  
  245.   /**
  246.    * Do not expand file and directory names
  247.    * Useful when using KoStore on non-KOffice files.
  248.    * (This method should be called just after the constructor)
  249.    */
  250.   void disallowNameExpansion( void );
  251.  
  252. protected:
  253.  
  254.   KoStore() {}
  255.  
  256.   /**
  257.    * Init store - called by constructor.
  258.    * @return true on success
  259.    */
  260.   virtual bool init( Mode mode );
  261.   /**
  262.    * Open the file @p name in the store, for writing
  263.    * On success, this method must set m_stream to a stream in which we can write.
  264.    * @param name "absolute path" (in the archive) to the file to open
  265.    * @return true on success
  266.    */
  267.   virtual bool openWrite( const QString& name ) = 0;
  268.   /**
  269.    * Open the file @p name in the store, for reading.
  270.    * On success, this method must set m_stream to a stream from which we can read,
  271.    * as well as setting m_iSize to the size of the file.
  272.    * @param name "absolute path" (in the archive) to the file to open
  273.    * @return true on success
  274.    */
  275.   virtual bool openRead( const QString& name ) = 0;
  276.  
  277.   /**
  278.    * @return true on success
  279.    */
  280.   virtual bool closeRead() = 0;
  281.   /**
  282.    * @return true on success
  283.    */
  284.   virtual bool closeWrite() = 0;
  285.  
  286.   /**
  287.    * Enter a subdirectory of the current directory.
  288.    * The directory might not exist yet in Write mode.
  289.    */
  290.   virtual bool enterRelativeDirectory( const QString& dirName ) = 0;
  291.   /**
  292.    * Enter a directory where we've been before.
  293.    * It is guaranteed to always exist.
  294.    */
  295.   virtual bool enterAbsoluteDirectory( const QString& path ) = 0;
  296.  
  297.   /**
  298.    * Check if a file exists inside the store.
  299.    * @param absPath the absolute path inside the store, i.e. not relative to the current directory
  300.    */
  301.   virtual bool fileExists( const QString& absPath ) const = 0;
  302.  
  303. private:
  304.   static Backend determineBackend( QIODevice* dev );
  305.  
  306.   /**
  307.    * Conversion routine
  308.    * @param _internalNaming name used internally : "root", "tar:/0", ...
  309.    * @return the name used in the file, more user-friendly ("maindoc.xml",
  310.    *         "part0/maindoc.xml", ...)
  311.    * Examples:
  312.    *
  313.    * tar:/0 is saved as part0/maindoc.xml
  314.    * tar:/0/1 is saved as part0/part1/maindoc.xml
  315.    * tar:/0/1/pictures/picture0.png is saved as part0/part1/pictures/picture0.png
  316.    *
  317.    * see specification (koffice/lib/store/SPEC) for details.
  318.    */
  319.   QString toExternalNaming( const QString & _internalNaming ) const;
  320.  
  321.   /**
  322.    *  Expands a full path name for a stream (directories+filename)
  323.    */
  324.   QString expandEncodedPath( QString intern ) const;
  325.  
  326.   /**
  327.    * Expands only directory names(!)
  328.    * Needed for the path handling code, as we only operate on internal names
  329.    */
  330.   QString expandEncodedDirectory( QString intern ) const;
  331.  
  332.   mutable enum
  333.   {
  334.       NAMING_VERSION_2_1,
  335.       NAMING_VERSION_2_2,
  336.       NAMING_VERSION_RAW  ///< Never expand file and directory names
  337.   } m_namingVersion;
  338.  
  339.   /**
  340.    * Enter *one* single directory. Nothing like foo/bar/bleh allowed.
  341.    * Performs some checking when in Read mode
  342.    */
  343.   bool enterDirectoryInternal( const QString& directory );
  344.  
  345. protected:
  346.  
  347.   Mode m_mode;
  348.  
  349.   /// Store the filenames (with full path inside the archive) when writing, to avoid duplicates
  350.   QStringList m_strFiles;
  351.  
  352.   /// The "current directory" (path)
  353.   QStringList m_currentPath;
  354.  
  355.   /// Used to push/pop directories to make it easy to save/restore the state
  356.   QValueStack<QString> m_directoryStack;
  357.  
  358.   /// Current filename (between an open() and a close())
  359.   QString m_sName;
  360.   /// Current size of the file named m_sName
  361.   QIODevice::Offset m_iSize;
  362.  
  363.   /// The stream for the current read or write operation
  364.   QIODevice * m_stream;
  365.  
  366.   bool m_bIsOpen;
  367.   /// Must be set by the constructor.
  368.   bool m_bGood;
  369.  
  370.   static const int s_area;
  371.  
  372. private:
  373.   KoStore( const KoStore& store );  ///< don't copy
  374.   KoStore& operator=( const KoStore& store );  ///< don't assign
  375.  
  376.   class Private;
  377.   Private * d;
  378.  
  379. };
  380.  
  381. #endif
  382.